package debtbundler.domain.entity;

import java.util.Set;

/**
 * A cost that is shared between persons.
 * <p> 
 * A shared is typically something that has been purchased, for example 
 * food, gas, alcohol, etc. As a money pool, it can also represent a loan or 
 * a money pool of a poker game.
 * <p>
 * The value of a shared cost comes from {@link Payment}s for it while
 * {@link Share}s determine how the cost should be shared between persons.  
 * 
 * @author Anssi
 *
 */
public interface SharedCost extends MoneyPool, Valuable {
		
	/**
	 * @param name	name of this shared cost
	 */
	public void setName(String name);
	
	/**
	 * Returns the payments of this shared cost.
	 *  
	 * @return	payments for this shared cost
	 */
	public Set<Payment> getPayments();	

	/**
	 * Returns the shares balancing the costs of this sharedCost. 
	 *  
	 * @return	 how the costs of this sharedCost are shared
	 */	
	public Set<Share> getShares();	

	/**
	 * Adds a partial payment paid by a person for this shared cost.
	 * <p> 
	 * For data consistency, implementations of this interface must make 
	 * sure that the payment is also added to the person.
	 * 
	 * @param payment
	 * 	the payment to add
	 * @return				
	 * 	<code>true</code> if the payment was added
	 */
	public boolean addPayment(Payment payment);

	/**
	 * Adds a person's share of total costs of this sharedCost.
	 * <p> 
	 * For data consistency, implementations of this interface must make 
	 * sure that the share is also added to the person.
	 * 
	 * @param share
	 * 	the share to add
	 * @return				
	 * 	<code>true</code> if the share was added
	 */
	public boolean addShare(Share share);	
	
	/**
	 * Returns the sum of costs and shares of this sharedCost. Costs are
	 * valued as positive, shares as negative. Therefore, a positive
	 * value means the costs are not properly shared, a negative value
	 * means someone has paid too much. 
	 * 
	 * @return	the sum of costs and shares of this sharedCost
	 * @see isBalanced()
	 */
	public double getBalance();	
	
	/**
	 * Returns the total value of this shared cost, that is 
	 * the sum of payments for it. 
	 * 
	 * @return	the total value of this cost
	 */
	@Override
	public double getValue();
	
	/**
	 * Shares this cost equally between participants. 
	 * <p>
	 * Existing <code>Share</code>s for this cost are
	 * removed and new <code>Share</code>s with equal
	 * value are calculated.
	 * 
	 * @param participants	participants to share this cost
	 * @return				the value of share per person
	 * @see getTotalCost()
	 */
	public double shareEqually(Set<Person> participants);
	
}
